home *** CD-ROM | disk | FTP | other *** search
/ The Atari Compendium / The Atari Compendium (Toad Computers) (1994).iso / files / umich / utils / tosfixes / hsmoda05.lzh / HSM_DOKU / PROG_MAN.TXT < prev    next >
Text File  |  1994-12-30  |  7KB  |  155 lines
  1. Programmers Manual for SERSOFST.TXT-compatible drivers
  2. ======================================================
  3.  
  4. Dies ist in Englisch geschrieben, weil anscheinend besonders die nicht 
  5. deutsch sprechenden Programmierer besondere Schwierigkeiten haben. Man mag 
  6. darüber denken, wie man will.
  7.  
  8. Because the non-German developers seems to have more difficulties than the 
  9. Germans, this text is in English language.
  10.  
  11. It is a _quick_ collection of some hints. I repeat me: I'm not payed for 
  12. doing this and it would be very nice, if I would get some sample code or 
  13. so from other people.
  14.  
  15.  
  16. Literature
  17. ----------
  18. A real programmer should read the SERSOFST.TXT, the RSVF_COO.TXT and the 
  19. text files of drivers and DRVIN.
  20.  
  21.  
  22. BIOS/XBIOS versus GEMDOS
  23. ------------------------
  24. At the moment you may mix GEMDOS-calls and BIOS/XBIOS-calls for one 
  25. port. But I recommend only to use the GEMDOS-calls, if you like to write a 
  26. "nice" program. I you maintain an old program (which uses only (X)BIOS 
  27. and direct hardware accesses), and you like to make it 
  28. "clean", then it should have a user-selectable possibility only to use 
  29. (X)BIOS and _not_ to access the hardware directly.
  30.  
  31.  
  32. GEMDOS and the AUX
  33. ------------------
  34. Atari recommends not to use the GEMDOS-AUX, especially the GEMDOS-calls 
  35. number 3, 4, 18, 19. I recommend too not to use this calls and even not to 
  36. use the "AUX:" or "U:\DEV\AUX", because this dirty things aren't 
  37. supported, that means, they remain very slow under TOS. GEMDOS number 3, 
  38. 4, 18, 19 is the slowest way, because your program does an trap#1 to the 
  39. gemdos and the gemdos does a trap#13 to the bios (for bios device number 
  40. 1). Additionally, that means that the GEMDOS could redirect this calls to 
  41. another thing and the BIOS could do it again. If you use these 
  42. gemdos-calls despite all warnings, you have to set the correct interface 
  43. configuration via XBIOS Rsconf, and the correct BIOS device via Bconmap 
  44. (if available).
  45.  
  46.  
  47. Opening a port
  48. --------------
  49. If there is a RSVF-cookie (see RSVF_COO.TXT) then you can find out which 
  50. ports are availabe and which GEMDOS-names and BIOS-numbers they have. 
  51. Mostly there will be a MODEM1.
  52.  
  53. You get a handle for this by using the GEMDOS-Fopen-function called with 
  54. the name "U:\DEV\MODEM1". (C-Programmers: double the backslashs). This 
  55. will work if DRVIN (and the driver) is installed, under MiNT, unter MagiC.
  56.  
  57. Handling the I/O-ports like files is the normal way under many modern 
  58. operating systems. And it is a fast way, because you can transfer many 
  59. characters at on call.
  60.  
  61.  
  62. Using the handle
  63. ----------------
  64. Please read the SERSOFST.TXT. It explains nearly everything.
  65.  
  66. Some remarks: Fread and Fwrite work normally in a non-blocking mode, that 
  67. means if you pass more bytes to Fwrite than actually can be transfered 
  68. into the transmitter buffer (from the buffer they are transmitted by an 
  69. interrupt routine or any other way not interesting for the application 
  70. programmer), then the first n bytes will be transfered (n = as much as fit 
  71. into the buffer) and Fwrite returns this n. This is the same behavior 
  72. which shows Fwrite if you try to write to a disk which becomes full. And 
  73. in a multitask system an other task could delete a file on the disk and a 
  74. subsequent Fwrite will write again some bytes, the same way it works on 
  75. this I/O-ports.
  76.  
  77. If you request more bytes than actually available via Fread, then Fread 
  78. will return as much bytes as available and the number of bytes. The same 
  79. way as trying to read more bytes from a file on disk then being in this 
  80. file.
  81.  
  82.  
  83. Why this SERSOFST.TXT-standard?
  84. -------------------------------
  85. I think it's explained in the SERSOFST.TXT. Again: It makes programs fast 
  86. (faster than using only BIOS at the clean way) and independend form the 
  87. underlaying hardware. All good Atari-emulators provide a 
  88. SERSOFST-compatible interface for the serial ports, that is my personal 
  89. opinion (yes, there are even bad emulators. That is my personal opinion. 
  90. Harun Scheutzow. Ask for SERSOFST.TXT/HSMODA-support :-) ). And if your 
  91. program is clean, using the SERSOFST-stuff, it will run on every port, no 
  92. matter whether this port is a MFP, a SCC, a 82550-FIFO-UART, an ACIA, some 
  93. mystic hardware of an Atari-emulator, or even an emulated modem via a 
  94. large network.
  95.  
  96. Using clean programs (as Connect, GSZRZ, a self written Midicom-driver and 
  97. so on) I had some successes even on unusual hardware: the programs runned 
  98. correctly without any change on the Macintosh with the MagiCMac. The only 
  99. precondition was the SERSOFST-conform driver for that hardware.
  100.  
  101.  
  102. Speed
  103. -----
  104. Some people believe that serial communications have to be slow all the 
  105. time. But even an old 8MHz-ST can transmit more than 15000cps 
  106. (15KByte/second) via a SERSOFST-compatible driver using a well implemented 
  107. Zmodem. This speeds become interesting for ISDN (or servicing more than 
  108. one modem per computer).
  109.  
  110.  
  111. Buffer sizes and XBIOS Iorec
  112. ----------------------------
  113. As long as (or if) the Fcntl TIOCBUFFER isn't implemented (that means it 
  114. returns an error if requesting the actual buffer sizes), it is legal to 
  115. change the size and address and water marks of buffers directly in the 
  116. IOREC. The clean way for this direct access: Switch to "no handshake", 
  117. disable the interrupts, change the buffers, re-enable the interrupts, 
  118. switch to the old handshake mode.
  119.  
  120.  
  121. DTR on MODEM2/SERIAL2 via direct access, The SCC
  122. ------------------------------------------------
  123. (ugly things not directly associated with SERSOFST)
  124. The Atari developer documentation is _very_ _wrong_. If you use the 
  125. drivers you aren't in need of accessing DTR directly in the hardware. But 
  126. if you do it, do it in the _only_ _one_ correct way:
  127.  
  128. disable interrupts
  129. get the WR5-shadow-register from IOREC(of this port)+$1D (it is a byte)
  130. modify this shadow and write it back into the IOREC
  131. select WR5 in the SCC
  132. write the shadow into the SCC (WR5)
  133. re-enable interrupts (restore old state)
  134.  
  135. This shadow exists because it's impossible on normal SCCs to read WR5 (and 
  136. even on enhanced SCCs it is difficult and slow). This shadow exist for 
  137. MODEM2 and SERIAL2 (the SCC ports) in all TOS-versions and MagiC and even 
  138. the SERSOFST-drivers (for compatibility).
  139.  
  140. HINT! Disable the interrupts every time you like to access a SCC-register 
  141. other than RR0, WR0 and the data-register (directly, not via WR8/RR8). If 
  142. you forget it, and your program wrote the register number into WR0, there 
  143. may come an interrupt and access the SCC too, producing trouble, because 
  144. the SCC thinks the value the interrupt routine writes to WR0 is some data 
  145. and not a new register number, returning to your program the trouble 
  146. continues. (The only way to end it: read from RR0, and forgetting the read 
  147. data. You can read/write from/to RR0/WR0 without first writing a 0 to WR0, 
  148. if you look into the TOS, you see that it writes 0es, this is nonsens, 
  149. forget this senceless behavior!)
  150.  
  151.  
  152.  
  153.  
  154. Harun Scheutzow, 1994-11-25
  155.